home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / ondestroy.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  3.2 KB  |  117 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 2000, 2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: ondestroy.h,v 1.8.18.2 2005/04/29 00:17:00 marka Exp $ */
  19.  
  20. #ifndef ISC_ONDESTROY_H
  21. #define ISC_ONDESTROY_H 1
  22.  
  23. #include <isc/lang.h>
  24. #include <isc/types.h>
  25.  
  26. ISC_LANG_BEGINDECLS
  27.  
  28. /*! \file 
  29.  * ondestroy handling.
  30.  *
  31.  * Any class ``X'' of objects that wants to send out notifications
  32.  * on its destruction should declare a field of type isc_ondestroy_t
  33.  * (call it 'ondest').
  34.  *
  35.  * \code
  36.  *     typedef struct {
  37.  *         ...
  38.  *         isc_ondestroy_t    ondest;
  39.  *         ...
  40.  *     } X;
  41.  * \endcode
  42.  *
  43.  * When an object ``A'' of type X is created
  44.  * it must initialize the field ondest with a call to
  45.  *
  46.  * \code
  47.  *     isc_ondestroy_init(&A->ondest).
  48.  * \endcode
  49.  *
  50.  * X should also provide a registration function for third-party
  51.  * objects to call to register their interest in being told about
  52.  * the destruction of a particular instance of X.
  53.  *
  54.  * \code
  55.  *    isc_result_t
  56.  *     X_ondestroy(X *instance, isc_task_t *task,
  57.  *              isc_event_t **eventp) {
  58.  *         return(isc_ondestroy_register(&instance->ondest, task,eventp));
  59.  *     }
  60.  * \endcode
  61.  *
  62.  *    Note: locking of the ondestory structure embedded inside of X, is
  63.  *     X's responsibility.
  64.  *
  65.  * When an instance of X is destroyed, a call to  isc_ondestroy_notify()
  66.  * sends the notifications:
  67.  *
  68.  * \code
  69.  *    X *instance;
  70.  *    isc_ondestroy_t ondest = instance->ondest;
  71.  *
  72.  *    ... completely cleanup 'instance' here...
  73.  *
  74.  *     isc_ondestroy_notify(&ondest, instance);
  75.  * \endcode
  76.  *
  77.  *
  78.  * see lib/dns/zone.c for an ifdef'd-out example.
  79.  */
  80.  
  81. struct isc_ondestroy {
  82.     unsigned int magic;
  83.     isc_eventlist_t events;
  84. };
  85.  
  86. void
  87. isc_ondestroy_init(isc_ondestroy_t *ondest);
  88. /*%<
  89.  * Initialize the on ondest structure. *must* be called before first call
  90.  * to isc_ondestroy_register().
  91.  */
  92.  
  93. isc_result_t
  94. isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task,
  95.                isc_event_t **eventp);
  96.  
  97. /*%<
  98.  * Stores task and *eventp away inside *ondest.  Ownership of **event is
  99.  * taken from the caller (and *eventp is set to NULL). The task is attached
  100.  * to.
  101.  */
  102.  
  103. void
  104. isc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender);
  105. /*%<
  106.  * Dispatches the event(s) to the task(s) that were given in
  107.  * isc_ondestroy_register call(s) (done via calls to
  108.  * isc_task_sendanddetach()).  Before dispatch, the sender value of each
  109.  * event structure is set to the value of the sender paramater. The
  110.  * internal structures of the ondest parameter are cleaned out, so no other
  111.  * cleanup is needed.
  112.  */
  113.  
  114. ISC_LANG_ENDDECLS
  115.  
  116. #endif /* ISC_ONDESTROY_H */
  117.